tidb-cloud: add TopRU user guide in TiDB Cloud Clinic (Premium)#22760
tidb-cloud: add TopRU user guide in TiDB Cloud Clinic (Premium)#22760zimulala wants to merge 3 commits into
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
ti-chi-bot
Bot
added
missing-translation-status
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces documentation for the TopRU feature in TiDB Cloud Clinic, including a new detailed guide and updates to the Table of Contents and main Clinic documentation. The feature allows users to identify high resource unit (RU) consumption by SQL statements and database users. The review feedback focuses on improving the documentation's clarity and adherence to the style guide by suggesting the use of active voice, removing redundant phrasing, and ensuring technical terms like TopN and sql_digest are properly formatted with backticks.
|
@zimulala: The following test failed, say
Full PR test history. Your PR dashboard. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here. |
| @@ -0,0 +1,124 @@ | |||
| --- | |||
| title: TopRU views in Top SQL in TiDB Cloud Clinic | |||
There was a problem hiding this comment.
| title: TopRU views in Top SQL in TiDB Cloud Clinic | |
| title: Top RU on TiDB Cloud Web Console for Premium&Essential |
| @@ -0,0 +1,124 @@ | |||
| --- | |||
| title: TopRU views in Top SQL in TiDB Cloud Clinic | |||
| summary: Learn how to use TopRU in TiDB Cloud Clinic to identify SQL statements and database users with high RU consumption. | |||
There was a problem hiding this comment.
| summary: Learn how to use TopRU in TiDB Cloud Clinic to identify SQL statements and database users with high RU consumption. | |
| summary: Learn how to use Top RU on TiDB Cloud Web Console to identify SQL statements and database users with high RU consumption. |
| summary: Learn how to use TopRU in TiDB Cloud Clinic to identify SQL statements and database users with high RU consumption. | ||
| --- | ||
|
|
||
| # TopRU views in Top SQL in TiDB Cloud Clinic |
There was a problem hiding this comment.
| # TopRU views in Top SQL in TiDB Cloud Clinic | |
| # Top RU on TiDB Cloud Web Console for Premium&Essential |
|
|
||
| # TopRU views in Top SQL in TiDB Cloud Clinic | ||
|
|
||
| TopRU is an SQL observability feature in the Top SQL page of TiDB Cloud Clinic. It ranks SQL workloads by request unit (RU) consumption to help you quickly identify SQL statements with high resource usage. |
There was a problem hiding this comment.
| TopRU is an SQL observability feature in the Top SQL page of TiDB Cloud Clinic. It ranks SQL workloads by request unit (RU) consumption to help you quickly identify SQL statements with high resource usage. | |
| Top RU is an SQL observability feature on TiDB Cloud Web Console. It ranks SQL workloads by request unit (RU) consumption to help you quickly identify SQL statements with high resource usage. |
|
|
||
| TopRU is an SQL observability feature in the Top SQL page of TiDB Cloud Clinic. It ranks SQL workloads by request unit (RU) consumption to help you quickly identify SQL statements with high resource usage. | ||
|
|
||
| TopRU reuses the Top SQL collection and reporting pipeline, but extends the core metric from CPU to RU, and aggregates records by `(user, sql_digest, plan_digest)`. This helps you identify both high-cost SQL statements and the database users who continuously consume RU. |
There was a problem hiding this comment.
| TopRU reuses the Top SQL collection and reporting pipeline, but extends the core metric from CPU to RU, and aggregates records by `(user, sql_digest, plan_digest)`. This helps you identify both high-cost SQL statements and the database users who continuously consume RU. | |
| Top RU reuses the Top SQL collection and reporting pipeline, but extends the core metric from CPU to RU, and aggregates records by `(user, sql_digest, plan_digest)`. This helps you identify both high-cost SQL statements and the database users who continuously consume RU. |
| - Is an RU spike in a time range caused by a small set of users or SQL statements? | ||
| - Why is resource consumption high even when CPU usage is not high? | ||
|
|
||
| TopRU data comes from runtime RU statistics in SQL execution, so it can reflect near-real-time resource trends. To control overhead, TopRU applies `TopN` aggregation to users and SQL statements, and merges low-priority items instead of outputting a full per-statement stream. |
There was a problem hiding this comment.
| TopRU data comes from runtime RU statistics in SQL execution, so it can reflect near-real-time resource trends. To control overhead, TopRU applies `TopN` aggregation to users and SQL statements, and merges low-priority items instead of outputting a full per-statement stream. | |
| Top RU data comes from runtime RU statistics in SQL execution, so it can reflect near-real-time resource trends. To control overhead, Top RU applies `TopN` aggregation to users and SQL statements, and merges low-priority items instead of outputting a full per-statement stream. |
|
|
||
| ## Recommended scenarios | ||
|
|
||
| TopRU is useful in the following scenarios: |
There was a problem hiding this comment.
| TopRU is useful in the following scenarios: | |
| Top RU is useful in the following scenarios: |
| - You need user-level visibility to answer "who is consuming RU" instead of only "which SQL consumes CPU". | ||
| - You need to quickly identify major RU hotspots under high load and prioritize SQL optimization, resource group governance, or workload throttling. | ||
|
|
||
| TopRU is not for the following scenarios: |
There was a problem hiding this comment.
| TopRU is not for the following scenarios: | |
| Top RU is not for the following scenarios: |
| TopRU is not for the following scenarios: | ||
|
|
||
| - Billing, reconciliation, or precise auditing. | ||
| - Replacing slow query logs, `statements_summary`, or daily offline statistics from resource groups. |
There was a problem hiding this comment.
| - Replacing slow query logs, `statements_summary`, or daily offline statistics from resource groups. | |
| - Replacing Slow Query, SQL Statement, or daily offline statistics from resource groups. |
|
|
||
| ## Prerequisites | ||
|
|
||
| Before using TopRU, make sure that all of the following conditions are met: |
There was a problem hiding this comment.
| Before using TopRU, make sure that all of the following conditions are met: | |
| Before using Top RU, make sure that all of the following conditions are met: |
huoyao1125
left a comment
huoyao1125
left a comment
There was a problem hiding this comment.
Overall Review
This PR has several critical issues that need to be addressed before merging:
-
Wrong product surface: Top RU is a feature in the TiDB Cloud web console, not in TiDB Cloud Clinic. The entire doc is filed under
tidb-cloud/premium/(Clinic Premium), which is incorrect. It should be a standalone page in the main TiDB Cloud web console docs (e.g.,tidb-cloud/top-ru.md). -
Essential tier completely missing: The product spec explicitly supports both Premium and Essential product tiers with different capabilities. This doc only covers Dedicated/Premium.
-
Internal perspective instead of user perspective: Several sections describe internal implementation details (aggregation keys, pipeline reuse, TopN compression algorithm) that belong in engineering design docs, not user-facing documentation. Users need to know what they can do and why, not how it works internally.
-
Key features missing from spec:
- Rank by Users panel (added in V1.4, Jan 7 2026) - not documented at all
- Top N configuration per tier: Premium default 10 (options: 20/50/100); Essential default 5 (options: 10/20)
- Data retention per tier: Premium 30 days; Essential 7 days
- Time range options: preset options + custom range with 24-hour max window constraint
- Drill-down plan scenarios: 4 scenarios based on plan availability are not fully covered
- Quick link from Query template ID to Slow Query logs
-
Prerequisite "Resource Control enabled" is incorrect: Top RU is a product-level observability feature available on Premium/Essential clusters. Users do not need to manually enable Resource Control for Top RU to work.
2 participants
What is changed, added or deleted? (Required)
This PR adds full TopRU user documentation for TiDB Cloud Clinic (Premium/Dedicated scope), instead of only adding a link.
Changes include:
tidb-cloud/premium/top-ru-in-clinic-premium.mdTOC-tidb-cloud-premium.mdtidb-cloud/premium/_index.mdtidb-cloud/tidb-cloud-clinic.mdto include TopRU entry and section.media/tidb-cloud/.Which TiDB version(s) do your changes apply to? (Required)
What is the related PR or file link(s)?
Do your changes match any of the following descriptions?